Ficha técnica

Escopos necessários

O token para consumir esta API deve ser gerado usando o Authorization Code.

O escopo openid é obrigatório. Ele permite consultar o perfil do usuário BTG com acesso à conta.

É necessário incluir o seguinte escopo:

Escopo	Descrição
brn:btg:empresas:banking:collections	Permite a consulta e gestão de pagamentos, lotes e contas

Ambiente de sandbox

Esta API está disponível apenas no sandbox (api.sandbox.empresas.btgpactual.com), um ambiente de testes para você construir e validar sua integração antes de operar com dados reais.

• Nada do que você faz aqui movimenta dinheiro de verdade.
• Tudo o que você cria pode ser consultado depois pelo id devolvido.
• Os dados de teste podem ser reiniciados periodicamente.
• Toda criação ou alteração deve enviar o header X-Idempotency-Key. Repetir a mesma chave devolve o mesmo resultado, sem duplicar a operação.

O que você pode fazer

• Pagamentos e comprovantes: pague por Pix, TED, boleto, DARF e outros meios, e obtenha o comprovante de cada pagamento concluído.
• Lotes: reúna vários pagamentos e dispare todos de uma só vez.
• Contas, saldo e extrato: consulte as contas da empresa, o saldo disponível e as movimentações.

O status de cada recurso é definido pela plataforma e nunca é informado por você.

Jornada de um pagamento

1. Consulte suas contas e o saldo. Identifique a conta de origem e confirme que há saldo disponível.
2. Inicie o pagamento. Informe o meio (por exemplo, Pix ou TED), o valor e os dados do favorecido. O pagamento nasce com um id.
3. Aguarde a aprovação, se necessária. Dependendo das regras da empresa, o pagamento fica em pending_approval até ser aprovado.
4. Acompanhe o resultado. Consulte o pagamento pelo id até que ele chegue a um estado final: settled (concluído), failed (recusado) ou canceled (cancelado por você).
5. Obtenha o comprovante. Para pagamentos concluídos, consulte o comprovante.
6. Confira no extrato. O pagamento aparece como débito nas movimentações da conta.

Enquanto o pagamento ainda não foi concluído, você pode cancelá-lo. Depois de settled, failed ou canceled, ele não aceita novas alterações, exceto a devolução de um pagamento já concluído.

Jornada de um lote

1. Abra um lote. Ele começa vazio e tem prazo e capacidade máxima de pagamentos.
2. Adicione pagamentos ao lote. Ao iniciar cada pagamento, informe o batchRef do lote. Os pagamentos só são disparados quando o lote for processado.
3. Processe o lote. Todos os pagamentos são disparados de uma só vez. Se o lote exigir aprovação, uma única aprovação libera todos os itens.
4. Acompanhe o andamento. O lote mostra quantos pagamentos já foram concluídos e, ao final, fica totalmente concluído ou parcialmente falho.
5. Abandone, se desistir. Um lote ainda não processado pode ser descartado sem disparar nenhum pagamento.

Como simular o andamento de um pagamento

No sandbox não há um banco real confirmando as operações. Para simular o que aconteceria em produção, use POST /{companyId}/banking/primitives/_sandbox/advance, informando o resourceId do pagamento e o event desejado:

event	Resultado no pagamento
settle	Pagamento concluído (settled)
fail	Recusado pelo meio de pagamento (failed)
require_approval	Aguardando aprovação (pending_approval)
approve	Aprovado (approved)
revert	Devolvido depois de concluído

Eventos de webhook

Em breve

Os webhooks desta API ainda não estão disponíveis. Por enquanto, acompanhe o andamento dos pagamentos e lotes consultando-os pelo id.

Quando forem liberados, você poderá receber notificações automáticas sobre as mudanças de status, sem precisar consultar repetidamente. Esta página será atualizada com a lista de eventos e seus payloads.